home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.1 (Developer) [x86] / NeXT Step 3.1 Intel dev.cdr.dmg / NextDeveloper / Headers / driverkit / IODisk.h < prev    next >
Encoding:
C/C++ Source or Header  |  1993-02-17  |  10.0 KB  |  377 lines
  1. /*     Copyright (c) 1991 NeXT Computer, Inc.  All rights reserved. 
  2.  *
  3.  * IODisk.h - Interface for generic Disk class.
  4.  *
  5.  * HISTORY
  6.  * 31-Jan-91    Doug Mitchell at NeXT
  7.  *      Created. 
  8.  */
  9.  
  10. #import <driverkit/return.h>
  11. #import <driverkit/IODevice.h>
  12. #import <bsd/sys/disktab.h>
  13. #import <kernserv/clock_timer.h>
  14.  
  15. #ifdef    KERNEL
  16. /*
  17.  * The Unix-level code associated with a particular subclass of IODisk
  18.  * keeps an array of these to allow mapping from a dev_t to a IODisk
  19.  * id. One per Unix unit (a unit is a physical disk). The _devAndIdInfo
  20.  * instance variable for an instances of a given class of IODisk 
  21.  * points to the one element in a static array of IODevToIdMap's for 
  22.  * that class.
  23.  */
  24. typedef struct {
  25.     id liveId;            // IODisk/... for live partition
  26.     id partitionId[NPART-1];    // for block and raw devices
  27.     dev_t rawDev;            // used by volCheck logic
  28.     dev_t blockDev;            // ditto
  29. } IODevAndIdInfo;
  30.  
  31. #endif    KERNEL
  32.  
  33. /*
  34.  * Basic "usefulness" state of drive.
  35.  */
  36. typedef enum {
  37.     IO_Ready,         // Ready for r/w operations
  38.     IO_NotReady,        // not ready (spinning up or busy)
  39.     IO_NoDisk,         // no disk present
  40.     IO_Ejecting        // eject in progress
  41. } IODiskReadyState;
  42.  
  43. /*
  44.  * Current known disk types.
  45.  */
  46. typedef enum {
  47.     IO_SCSI,
  48.     IO_Floppy,
  49.     IO_Other
  50. } IODiskType;
  51.  
  52. @interface IODisk:IODevice
  53. {
  54. @private
  55.     id        _nextLogicalDisk;    // next LogicalDisk object
  56.                         // in chain.
  57.                         // May be nil. 
  58.     unsigned    _blockSize;        // in bytes 
  59.     unsigned    _diskSize;        // in blockSize's
  60.     BOOL        _removable;        // removable media device 
  61.     BOOL        _formatted;        // disk is formatted
  62.     BOOL        _isPhysical;        // this is NOT a logical disk
  63.     BOOL        _writeProtected;
  64. #ifdef    KERNEL
  65.     IODevAndIdInfo    *_devAndIdInfo;        // provides dev_t to id 
  66.                         // mapping for this instance.
  67. #endif    KERNEL
  68.     id        _LogicalDiskLock;    // NXLock. Serializes
  69.                         // operations whcih change 
  70.                         // LogicalDisks attached to 
  71.                         // this device.
  72.     char        _driveName[MAXDNMLEN];    // for Unix 'drive_info'
  73.                         // requests 
  74.                         
  75.     /*
  76.      * The lastReadyState variable is initialized by device-specific
  77.      * subclass, but is subsequently only changed by the volCheck module.
  78.      */
  79.     IODiskReadyState _lastReadyState;    
  80.     
  81.     /*
  82.      * Statistics. Accessed en masse via 
  83.      * getIntValues::DISK_STATS_ARRAY.
  84.      * All times in ms.
  85.      */
  86.     unsigned    _readOps;
  87.     unsigned    _bytesRead;
  88.     unsigned    _readTotalTime;
  89.     unsigned    _readLatentTime;
  90.     unsigned    _readRetries;
  91.     unsigned    _readErrors;
  92.     unsigned    _writeOps;
  93.     unsigned     _bytesWritten;
  94.     unsigned    _writeTotalTime;
  95.     unsigned    _writeLatentTime;
  96.     unsigned    _writeRetries;
  97.     unsigned    _writeErrors;
  98.     unsigned    _otherRetries;
  99.     unsigned    _otherErrors;
  100. }
  101.  
  102. /*
  103.  * Register instance with current name space.  
  104.  */
  105. - registerDevice;        // nil return means failure
  106.  
  107. /*
  108.  * Public methods to get and set disk parameters. These are implemented in
  109.  * the IODisk class. 
  110.  */
  111. - (unsigned)diskSize;
  112. - (unsigned)blockSize;
  113. - (IOReturn)setFormatted : (BOOL)formattedFlag;
  114. - (BOOL)isFormatted;
  115. - (BOOL)isRemovable;
  116. - (BOOL)isPhysical;
  117. - (BOOL)isWriteProtected;
  118. - (const char *)driveName;
  119.  
  120. /*
  121.  * Two forms of eject - one for use with logical disks attached
  122.  * (eject), so that attached NXDisks can be polled for open 
  123.  * state; this method is implemented in IODisk but is normally overridden
  124.  * by a subclass like IODiskPartition. The other is ejectPhysical, 
  125.  * in the IOPhysicalDiskMethods protocol (below). 
  126.  */
  127. - (IOReturn) eject;
  128.  
  129. /*
  130.  * Get/set parameters used only by subclasses.
  131.  */              
  132. - (void)setDiskSize            : (unsigned)size;
  133. - (void)setBlockSize            : (unsigned)size;
  134. - (void)setIsPhysical            : (BOOL)isPhysical;
  135. - nextLogicalDisk;
  136. - (void)setRemovable            : (BOOL)removableFlag;
  137. - (void)setDriveName            : (const char *)name;
  138. - (IODiskReadyState)lastReadyState;
  139. - (void)setLastReadyState        : (IODiskReadyState)readyState;
  140. - (void)setWriteProtected        : (BOOL)writeProtectFlag;
  141. - (void)setFormattedInternal         : (BOOL)formattedFlag;
  142.  
  143. /*
  144.  * Statistics support.
  145.  *
  146.  * These methods are invoked by subclass during I/O.
  147.  */
  148. - (void)addToBytesRead        : (unsigned)bytesRead
  149.                   totalTime  : (ns_time_t)totalTime
  150.                   latentTime : (ns_time_t)latentTime;
  151. - (void)addToBytesWritten    : (unsigned)bytesWritten
  152.                   totalTime  : (ns_time_t)totalTime
  153.                   latentTime : (ns_time_t)latentTime;
  154. - (void)incrementReadRetries;
  155. - (void)incrementReadErrors;
  156. - (void)incrementWriteRetries;
  157. - (void)incrementWriteErrors;
  158. - (void)incrementOtherRetries;
  159. - (void)incrementOtherErrors;
  160.  
  161. /*
  162.  * For gathering cumulative statistics.
  163.  */
  164. - (IOReturn)getIntValues        : (unsigned *)parameterArray
  165.                forParameter : (IOParameterName)parameterName
  166.                       count : (unsigned *)count;    // in/out
  167.  
  168. /*
  169.  * Obtain statistics in array defined by IODiskStatIndices.
  170.  */
  171. #define IO_DISK_STATS        "IODiskStats"
  172.  
  173. /*
  174.  * RPC equivalent of isKindOfClassNamed:IODisk. Used in 
  175.  * getParameterInt. Returns no data; just returns IO_R_SUCCESS.
  176.  */
  177. #define IO_IS_A_DISK        "IOIsADisk"
  178.  
  179. /*
  180.  * RPC equivalent of _isPhysDevice. Used in getParameterInt. Returns one 
  181.  * int, the value of _isPhysDevice.
  182.  */
  183. #define IO_IS_A_PHYSICAL_DISK    "IOIsAPhysicalDisk"
  184.  
  185. /*
  186.  * Indices into array obtained via getParameterInt : IO_DISK_STATS.
  187.  */
  188. typedef enum {
  189.     IO_Reads,
  190.     IO_BytesRead,
  191.     IO_TotalReadTime,
  192.     IO_LatentReadTime,
  193.     IO_ReadRetries,
  194.     IO_ReadErrors,
  195.     IO_Writes,
  196.     IO_BytesWritten,
  197.     IO_TotalWriteTime,
  198.     IO_LatentWriteTime,
  199.     IO_WriteRetries,
  200.     IO_WriteErrors,
  201.     IO_OtherRetries,
  202.     IO_OtherErrors,
  203. } IODiskStatIndices;
  204.     
  205. #define IO_DISK_STAT_ARRAY_SIZE        (IO_OtherErrors + 1)
  206.  
  207. /*
  208.  * Register a connection with LogicalDisk.
  209.  */
  210. - (void) setLogicalDisk    : diskId;
  211.  
  212. /*
  213.  * Lock/Unlock device for LogicalDisk-specific methods. Invoked only by
  214.  * LogicalDisks which are attached to this device.
  215.  */
  216. - (void)lockLogicalDisks;
  217. - (void)unlockLogicalDisks;
  218.  
  219. /*
  220.  * Convert an IOReturn to text. Overrides superclass's method of same name
  221.  * to allow for additional IOReturn's defined in this file.
  222.  */
  223. - (const char *)stringFromReturn    : (IOReturn)rtn;
  224.  
  225. /*
  226.  * Request a "please insert disk" panel.
  227.  */
  228. - (void)requestInsertionPanelForDiskType : (IODiskType)diskType;
  229.  
  230. /*
  231.  * Notify volCheck thread that specified device is in a "disk ejecting" state.
  232.  */
  233. - (void)diskIsEjecting : (IODiskType)diskType;
  234.  
  235. /*
  236.  * Notify volCheck that disk has gone not ready. Typically called on
  237.  * gross error detection.
  238.  */
  239. - (void)diskNotReady;
  240.  
  241. /*
  242.  * To be optionally overridden by subclass. IODisk version returns NO.
  243.  * If subclass's version returns NO, and the drive is a removable media 
  244.  * drive, the drive will not be polled once per second while ready state
  245.  * is IO_NotReady or IO_NoDisk; instead; polling will only occur when
  246.  * an DKIOCCHECKINSERT ioctl is executed on the vol driver.
  247.  */
  248. - (BOOL)needsManualPolling;
  249.  
  250. @end
  251.  
  252. /* End of IODisk interface. */
  253.  
  254. /*
  255.  * The IOPhysicalDiskMethods protocol must be implemented by each bottom-level 
  256.  * physical disk subclass of IODisk.
  257.  */
  258.  
  259. @protocol IOPhysicalDiskMethods
  260.  
  261. /*
  262.  * Get physical parameters (dev_size, block_size, etc.) from new disk. Called 
  263.  * upon disk insertion detection or other transition to RS_READY.
  264.  */
  265. - (IOReturn)updatePhysicalParameters;
  266.  
  267. /*
  268.  * Called by volCheck thread when WS has told us that a requested disk is
  269.  * not present. Pending I/Os which require a disk to be present must be 
  270.  * aborted.
  271.  */
  272. - (void)abortRequest;
  273.  
  274. /*
  275.  * Called by the volCheck thread when a transition to "ready" is detected.
  276.  * Pending I/Os which require a disk may proceed.
  277.  */
  278. - (void)diskBecameReady;
  279.  
  280. /*
  281.  * Inquire if disk is present; if not, and 'prompt' is TRUE, ask for it. 
  282.  * Returns IO_R_NODISK if:
  283.  *    prompt TRUE, disk not present, and user cancels request for disk.
  284.  *    prompt FALSE, disk not present.
  285.  * Else returns IO_R_SUCCESS.
  286.  */
  287. - (IOReturn)isDiskReady    : (BOOL)prompt;
  288.  
  289. /*
  290.  * Device-specific eject method, only called on physical device.
  291.  */
  292. - (IOReturn) ejectPhysical;
  293.  
  294. /*
  295.  * Determine basic state of device. This method should NOT implement any
  296.  * retries. It also should not return RS_EJECTING (That's only used in the
  297.  * lastReadyState instance variable).
  298.  */
  299. - (IODiskReadyState)updateReadyState;
  300.  
  301. @end
  302.  
  303. /* end of IOPhysicalDiskMethods protocol */
  304.  
  305. /*
  306.  * Standard IODisk read/write protocol. Offsets are in blocks.
  307.  * Lengths are in bytes.
  308.  * FIXME - readAsyncAt should NOT copy data back to caller on return in
  309.  * Distrubuted Objects implementation.
  310.  */
  311. @protocol IODiskReadingAndWriting
  312.  
  313. #ifndef    KERNEL
  314.  
  315. - (IOReturn) readAt        : (unsigned)offset 
  316.                   length : (unsigned)length 
  317.                   buffer : (unsigned char *)buffer
  318.                   actualLength : (unsigned *)actualLength;
  319.                   
  320. - (IOReturn) readAsyncAt    : (unsigned)offset 
  321.                   length : (unsigned)length 
  322.                   buffer : (unsigned char *)buffer
  323.                   pending : (void *)pending;    // untyped
  324.                   
  325. - (IOReturn) writeAt        : (unsigned)offset 
  326.                   length : (unsigned)length 
  327.                   buffer : (unsigned char *)buffer
  328.                   actualLength : (unsigned *)actualLength;
  329.                       
  330. - (IOReturn) writeAsyncAt    : (unsigned)offset 
  331.                   length : (unsigned)length 
  332.                   buffer : (unsigned char *)buffer
  333.                   pending : (void *)pending;
  334. #else    KERNEL
  335.  
  336. - (IOReturn) readAt        : (unsigned)offset 
  337.                   length : (unsigned)length 
  338.                   buffer : (unsigned char *)buffer
  339.                   actualLength : (unsigned *)actualLength 
  340.                   client : (vm_task_t)client;
  341.  
  342. - (IOReturn) readAsyncAt    : (unsigned)offset 
  343.                   length : (unsigned)length 
  344.                   buffer : (unsigned char *)buffer
  345.                   pending : (void *)pending
  346.                   client : (vm_task_t)client;
  347.         
  348. - (IOReturn) writeAt        : (unsigned)offset 
  349.                   length : (unsigned)length 
  350.                   buffer : (unsigned char *)buffer
  351.                   actualLength : (unsigned *)actualLength 
  352.                   client : (vm_task_t)client;
  353.           
  354. - (IOReturn) writeAsyncAt    : (unsigned)offset 
  355.                   length : (unsigned)length 
  356.                   buffer : (unsigned char *)buffer
  357.                   pending : (void *)pending
  358.                   client : (vm_task_t)client;
  359.                   
  360. #endif    KERNEL
  361.  
  362. @end
  363.  
  364. /* end of DiskDeviceRw protocol */
  365.  
  366.  
  367. /*
  368.  * IOReturn's specific to IODisk.
  369.  */
  370. #define IO_R_NO_LABEL        (-1100)        /* no label present */
  371. #define IO_R_UNFORMATTED    (-1101)        /* disk not formatted */
  372. #define IO_R_NO_DISK        (-1102)        /* disk not present */
  373. #define IO_R_NO_BLOCK_ZERO    (-1103)        /* can't read first sector */
  374. #define IO_R_NO_NEXT_PART    (-1104)        /* No NeXT partition on */
  375.                         /* DOS disk */
  376. extern IONamedValue readyStateValues[];
  377.